feat(cli): forkd quickstart — zero-to-first-fork in one command#240
Merged
Conversation
publish-pypi.yml was failing with HTTP 400 'File already exists' when a v* tag got force-pushed (e.g. when fixing release.yml's Docker job for v0.5.2 — see #235). The publish step has nothing to do, but the action defaults to skip-existing=false, so the no-op surfaces as a failure. Set skip-existing=true: PyPI immutability means re-publish is a logical no-op anyway, and treating it as a hard error means every tag-fix dance leaves a red X behind that's actually a non-event. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Conversion-funnel work: stars are growing ~10x faster than downloads, and the most-cited reason is first-run friction (host setup, kernel download, snapshot bake, netns provisioning — four manual steps across two scripts and three verbs before the first fork). `sudo -E forkd quickstart` collapses that to one command: 1. doctor::preflight() — hard-gates on platform/KVM/firecracker; reports kernel/tap/docker as data rather than failures 2. Heals what's missing WITH CONSENT (or --yes): guest kernel download, tap creation, netns provisioning. The setup scripts are embedded via include_str! so a tarball install works without the repo checked out; an interactive prompt lists exactly what will be touched before anything runs. Nothing on the host changes without an explicit yes. 3. Snapshot: reuse existing > bake from python:3.12-slim via local Docker (preferred — uses *this host's* Firecracker, so the vmstate can never hit cross-FC-version restore errors) > hub pull fallback with a compat warning. 4. fork -n 10 --per-child-netns, then prints next steps. Idempotent: re-running skips completed setup and reuses the snapshot. README: new "One command" section at the top of Quick start; stale v0.3.4 tarball URLs bumped to v0.5.2. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Conversion-funnel work. Stars are growing ~10× faster than downloads; the most plausible culprit is first-run friction — today a new user crosses four manual steps over two scripts and three verbs before seeing their first fork. Every step is a place to bounce.
What
sudo -E forkd quickstartcollapses the whole path into one command:doctor::preflight()) — hard-gates on platform / hardware virt / KVM / firecracker binary; reports kernel / tap / Docker as routing data instead of failures.--yesfor CI). The repo's idempotent setup scripts are embedded viainclude_str!, so a tarball install works without a repo checkout. Nothing touches the host without an explicit yes — lesson learned from a recent incident where unprompted host networking changes caused real damage.quickstarttag > bake frompython:3.12-slimvia local Docker > hub pull fallback. Local bake is preferred because it uses this host's Firecracker — immune to the cross-FC-versionbitcode errorrestore failures that hub-distributed snapshots can hit (the exact failure mode from the bench: N=100 hugepage spawn numbers (deferred from #230) #234 yak-shave).-n 10 --per-child-netns, per-child timings, then next-step pointers (wider fan-out, exec, recipes).Idempotent: re-run reuses the snapshot and skips completed setup.
Also: README gets a "One command" section at the top of Quick start, and the stale v0.3.4 tarball URLs are bumped to v0.5.2.
Verification
cargo check/cargo clippy --all-targets -- -D warnings/cargo fmt --check: clean on the dev boxforkd quickstart --helprenders correctlyTest plan
🤖 Generated with Claude Code